<!doctype html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link rel="stylesheet" href="./../assets/css/combined.css">
	<link rel="shortcut icon" href="./../favicon.ico" />
	<script src="http://www.google.com/jsapi" type="text/javascript"></script>
	<script type="text/javascript">
		var path = './../';
	</script>
	<script src="./../assets/js/combined.js"></script>
	<title>Models - General - FuelPHP Documentation</title>
</head>
<body>
	<div id="container">
		<header id="header">
			<div class="table">
				<h1>
					<strong>FuelPHP, a PHP 5.3 Framework</strong>
					Documentation
				</h1>

				<form id="google_search">
					<p>
						<span id="search_clear">&nbsp;</span>
						<input type="submit" name="search_submit" id="search_submit" value="search" />
						<input type="text" value="" id="search_input" name="search_input" />
					</p>
				</form>
			</div>
			<nav>

				<div class="clear"></div>
			</nav>
			<a href="#" id="toc_handle">table of contents</a>
			<div class="clear"></div>
		</header>

		<div id="cse">
			<div id="cse_point"></div>
			<div id="cse_content"></div>
		</div>

		<div id="main">

			<h2>Models</h2>

			<h3>What are models?</h3>

			<p>
				Whenever data needs to be retrieved, manipulated or deleted this should always be done by a model. A Model is a representation of some kind of
				data and has the methods to change them. For example: you never put SQL queries in a Controller, those are put in the Model and the Controller will
				call upon the Model to execute the queries. This way if your database changes you won't need to change all your Controllers but just the Model that acts upon it.
			</p>

			<h3 id="using_models">How are Models used?</h3>

			<p>
				In Fuel a Model is essentially just a <a href="classes.html" title="Class Documentation">Class</a> like any other. They do nothing more than a library, but the Model_ prefix
				helps to differentiate it from other classes. To do something useful with a Model you will need to use other classes.
			</p>

			<h3 id="creating_models">Creating a model</h3>

			<pre class="php"><code>
namespace Model;

class Welcome extends \Model {

    public static function get_results()
    {
        // Database interactions
    }

}</code></pre>

			<p class="note">Remember to prefix a backslash to classes you're using from global, outside the namespace
				you're in. If you don't understand why, read up on namespaces on
				<a href="http://www.php.net/namespaces">PHP.net</a>.</p>

			<h3 id="accessing_models">Accessing a model</h3>

			<p>PHP has the <code>use</code> keyword for importing classes into the current namespace, this allows
				you to shorten the Model's classname from <code>Model\Welcome</code> to just <code>Welcome</code>
				within the file of a specific class:</p>

            <pre class="php"><code>
use \Model\Welcome;

class Controller_Welcome extends Controller
{
    public function action_index()
    {
        $results = Welcome::get_results();
    }
}   </code></pre>



			<h3 id="writing_own_models">Writing your own models</h3>

			<p>While models can be used with any type of data storage we'll focus here on usage with SQL because that's the
				most common usage. Almost always your models will have at least all <a href="http://en.wikipedia.org/wiki/Create,_read,_update_and_delete" target="_blank">CRUD</a>
				methods: create, read, update, delete (or variations on those). In Fuel your models don't need to extend
				anything by default, though you can of course create your own base model or use Fuel's
				<a href="#orm_models">Orm package</a>.</p>

			<h3 id="writing_queries">Writing SQL Queries</h3>

			<p>You can use the <a href="../classes/database/db.html">DB class</a> to build queries with native SQL like so:</p>

			<pre class="php"><code>DB::query('SELECT * FROM users WHERE id = 5');</code></pre>

			<h3 id="use_query_builder">Using the Query Builder</h3>

			<p>When it comes to escaping data, working with data in arrays or making an application portable over multiple database engines, you might find native
				SQL to be rather cumbersome. Using the Query Builder methods in the DB Class you can abstract writing native SQL:
			</p>

			<pre class="php"><code>DB::select('title','content')->from('articles')->execute()->get('title');</code></pre>

			<p>See more about native SQL queries and using the Query Builder in the <a href="../classes/database/db.html">DB class</a> documentation.</p>

			<h3 id="model_crud_models">Using Model_Crud to create models</h3>

			<p>One possible way of creating models is by using <a href="../classes/model_crud/introduction.html">Model_Crud</a>, which adds a commonly used functionality to your models for interacting with a database table. There's an example of its usage below.</p>

			<pre class="php"><code>// find all articles
$entry = Model_Article::find_all();

// find all articles from category 1 order descending by date
$entry = Model_Article::find(array(
    'where' => array('category_id', 1),
    'order_by' => array('date' => 'desc')
));</code></pre>

			<h3 id="orm_models">Using the Orm to create models</h3>

			<p>For models with more functionality, like support for relations, you can use the <a href="../packages/orm/intro.html">Orm Package</a>, which adds a lot of functionality out-of-the-box to your models. There's an example of its usage below.</p>

			<pre class="php"><code>// find all articles
$entry = Model_Article::find('all');

// find all articles from category 1 order descending by date
$entry = Model_Article::find('all', array(
    'where' => array('category_id', 1),
    'order_by' => array('date', 'desc')
));</code></pre>

			<p>Model_Crud and the ORM package use similar syntax, which makes it simple to migrate once you require more functionality than Model_Crud can provide.</p>

		</div>

		<footer>
			<p>
				&copy; FuelPHP Development Team 2010-2013 - <a href="http://fuelphp.com">FuelPHP</a> is released under the MIT license.
			</p>
		</footer>
	</div>
</body>
</html>
